SST ShlWAPI AssocGetPerceivedType Function

	(SST) ShlWAPI.pas Version 1.08

Developer Reference

(SST)ShlWAPI AssocGetPerceivedType Function
Determines into which category of file, files with the specified suffix/extension fall.

Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).

Syntax
function AssocGetPerceivedType(pszExt : LPCWSTR; VAR ptype : PERCEIVED; VAR pflag : PERCEIVEDFLAG; ppszType : LPWSTR) : HRESULT;

Parameters

pszExt [in]

Pointer to a null-terminated, Unicode string that is the file suffix/extension for which to retrieve the perceived type. This (extension) string should have the format of the file extension keys under the HKEY_CLASSES_ROOT key in the Windows registry, that is, including a leading period.

ptype [out]

A signed, 32-bit, integer variable of type PERCEIVED, into which the function should write the value that represents the category. This can take on one of the following values:

PERCEIVED_TYPE_CUSTOM	(= -3)	Although it is referred to in the remarks section of the doc. on the function and it is described as denoting that "the file's perceived type as defined in the registry is not a known type", this does little to elucidate this (ordinal) value's usage, particularly in light of the fact, that this is already amply covered by PERCEIVED_TYPE_UNSPECIFIED (and/or PERCEIVED_TYPE_UNKNOWN, if need be). It is, therefore, our assumption, that this value is meant to signify that it has a perceived type, but this has not yet been assigned an ordinal value in the PERCEIVED, enumerated type and/or the source of the assignation (registry, dll, etc.) cannot be determined. However, this remains to be clarified by Microsoft.
PERCEIVED_TYPE_UNSPECIFIED	(= -2)	The pertinent sources did not render any information on the perceived type of the specified suffix/extension.
PERCEIVED_TYPE_FOLDER	(= -1)	According to the Microsoft documentation this value is unused and should therefore not be returned.
PERCEIVED_TYPE_UNKNOWN	(= 0)	According to the Microsoft documentation, this value is an internal, initialization value that is never returned to the caller.
PERCEIVED_TYPE_TEXT	(= 1)	Files with this suffix/extension are assumed to contain largely or exclusively text.
PERCEIVED_TYPE_IMAGE	(= 2)	Files with this suffix/extension are perceived as having a graphic file format and/or being digitized pictures.
PERCEIVED_TYPE_AUDIO	(= 3)	Files with this suffix/extension are perceived as being files that are used to record, store, and/or reproduce sounds.
PERCEIVED_TYPE_VIDEO	(= 4)	Files with this suffix/extension are perceived as being files that are used to store, record, and/or reproduce a sequence of pictures.
PERCEIVED_TYPE_COMPRESSED	(= 5)	Files with this suffix/extension are perceived as having been reduced in size or supporting size reduction by means that preserve the essence of the file's contents.
PERCEIVED_TYPE_DOCUMENT	(= 6)	Files with this suffix/extension are files that were typically created by user-level software but don't fall into any of the other categories (e.g. text, video, etc.) Examples for file extensions that (commonly) fall into this category are .rtf and .doc.
PERCEIVED_TYPE_SYSTEM	(= 7)	This suffix/extension denotes files as an inherent part of or vital to the operating system.
PERCEIVED_TYPE_APPLICATION	(= 8)	The file suffix/extension is perceived as part of a software application. Note, that not only binary executables can fall into this category.
PERCEIVED_TYPE_GAMEMEDIA	(= 9)	?
PERCEIVED_TYPE_CONTACTS	(= 10)	Under Windows Vista and later, files with the specified suffix/extension are perceived as files that act as databases/containers for information that can be/is used to establish channels of communication between persons or hardware.

pflag [out]

Unsigned 32-bit variable of type PERCEIVEDFLAG that provides information on the level of support for files of this type and/or the source of the perceived type information. The returned information is written to this variable in form of one or a combination of the following bit-flags:

PERCEIVEDFLAG_UNDEFINED	(= 0x00)	The function was unable to determine a source of intormation on the perceived type for the specified file suffix/extension. Support for this particular suffix/extenison is therefore undefined.
PERCEIVEDFLAG_SOFTCODED	(= 0x01)	The type as which this file suffix/extension is perceived was resolved by reading the pertinent entries in the Windows registry.
PERCEIVEDFLAG_HARDCODED	(= 0x02)	This file suffix/extension is known to the operating system because it is hard-coded in one of the core system's executables (i.e. the system does not require information stored in files with variable content, such as registry, .ini. or .conf, files, to recognize the extension). This bit-flag is frequently encountered in combination with the PERCEIVEDFLAG_NATIVESUPPORT flag.
PERCEIVEDFLAG_NATIVESUPPORT	(= 0x04)	Support for files of this type is built into the operating system. This bit-flag is frequently encountered in combination with the PERCEIVEDFLAG_HARDCODED flag.
PERCEIVEDFLAG_GDIPLUS	(= 0x10)	Support for files of this type is provided through and requires the GDI+ dynamic link library (dll) (Gdiplus.dll). The file type is known because this module was either installed together with the operating system or as part of an update.
PERCEIVEDFLAG_WMSDK	(= 0x20)	The suffix/extension is recognized and supported by the Windows Media Format SDK modules.
PERCEIVEDFLAG_ZIPFOLDER	(= 0x40)	This file extension was recognized as belonging to a compressed file (e.g. .cab, .zip) type. Support for this file type may be an inherent part of the operating system or provided through third party software. The source for the perception of the file type therefore depends on the specific extension, operating system version, and the installed (third party) software. In this context it should be noted that, even though operating system support for .zip files was (only) introduced with Windows XP, the NT file system (NTFS) has supported compressed files/folders ever since the advent of Windows NT 3.51, even if this was restricted to files compressed with the Lempel-Ziv algorithm (i.e. .cab files).

ppszType [out]

Address of, or pointer to, a pointer variable that receives the address of a Unicode string, that contains the user friendly name of the category into which files with the specified extension fall.

Return Values
If the function was successful in determining a perceived type the return value is S_OK (= 0), if not, the returned value is a COM error code. Typically, this is 0x80070002 (= -2147024894) for unregistered file extensions and/or types for which perceived type information is not available.

Remarks
The function cannot be used to determine a specific file's perceived type. For example, if the function were called with "C:\Users\Public\Pictures\screen8.bmp", the function will fail because it was passed more than a suffix/extension as the first parameter.

Example
PROCEDURE TForm4.TestShlWAPIAssocGetPerceivedType(Sender : TObject); VAR apiretval : HRESULT; VAR wcharsuffix : WideString; VAR perceivedtype : PERCEIVED; VAR typeflag : PERCEIVEDFLAG; VAR wchartypestrp : PWideChar; VAR newinfoline : STRING; BEGIN apiretval := 0; wcharsuffix := ''; perceivedtype := 0; typeflag := 0; wchartypestrp := NIL; newinfoline := ''; wcharsuffix := '.txt'; newinfoline := 'AssocGetPerceivedType called for ' + '.txt'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.cpp'; newinfoline := 'AssocGetPerceivedType called for ' + '.cpp'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.hta'; newinfoline := 'AssocGetPerceivedType called for ' + '.hta'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.bmp'; newinfoline := 'AssocGetPerceivedType called for ' + '.bmp'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.wav'; newinfoline := 'AssocGetPerceivedType called for ' + '.wav'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.avi'; newinfoline := 'AssocGetPerceivedType called for ' + '.avi'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.doc'; newinfoline := 'AssocGetPerceivedType called for ' + '.doc'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.zip'; newinfoline := 'AssocGetPerceivedType called for ' + '.zip'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.sys'; newinfoline := 'AssocGetPerceivedType called for ' + '.sys'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); apiretval := 0; wcharsuffix := '.drv'; newinfoline := 'AssocGetPerceivedType called for ' + '.drv'; Memo1.Lines.Add(newinfoline); apiretval := AssocGetPerceivedType(PWideChar(wcharsuffix), perceivedtype, typeflag, @wchartypestrp); newinfoline := AnsiQuotedStr(wchartypestrp, '"'); newinfoline := newinfoline + ', perceived type : ' + IntToStr(perceivedtype) + ' perceived flag : 0x' + IntToHex(typeflag, 4); Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END;

AssocGetPerceivedType called for .txt "text", perceived type : 1 perceived flag : 0x0005 AssocGetPerceivedType called for .cpp "text", perceived type : 1 perceived flag : 0x0005 AssocGetPerceivedType called for .hta "application", perceived type : 8 perceived flag : 0x0002 AssocGetPerceivedType called for .bmp "image", perceived type : 2 perceived flag : 0x0016 AssocGetPerceivedType called for .wav "audio", perceived type : 3 perceived flag : 0x0026 AssocGetPerceivedType called for .avi "video", perceived type : 4 perceived flag : 0x0026 AssocGetPerceivedType called for .doc "document", perceived type : 6 perceived flag : 0x0001 AssocGetPerceivedType called for .zip "compressed", perceived type : 5 perceived flag : 0x0046 AssocGetPerceivedType called for .sys "system", perceived type : 7 perceived flag : 0x0001 AssocGetPerceivedType called for .drv "system", perceived type : 7 perceived flag : 0x0001

Requirements
Unit:	Declared and imported in (SST)ShlWAPI.pas
Library:	(SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode:	Implemented as Unicode (AssocGetPerceivedType) function only.
Min. ShlWAPI.dll version according to MS SDK doc.:	6.0
Min. ShlWAPI.dll version based on SST research:	6.0
Min. OS version(s) according to Microsoft SDK doc.:	Windows XP Service Pack 2 (SP2)
Min. OS version(s) according to SST research.:	Windows XP/Server 2003 with Service Pack 2 (SP2)